.TH "dsr2xml" 1 "Tue Dec 19 2023" "Version 3.6.8" "OFFIS DCMTK" \" -*- nroff -*-
.nh
.SH NAME
dsr2xml \- Convert DICOM SR file and data set to XML

.SH "SYNOPSIS"
.PP
.PP
.nf
dsr2xml [options] dsrfile-in [xmlfile-out]
.fi
.PP
.SH "DESCRIPTION"
.PP
The \fBdsr2xml\fP utility converts the contents of a DICOM Structured Reporting (SR) document (file format or raw data set) to XML (Extensible Markup Language)\&. The XML Schema \fIdsr2xml\&.xsd\fP does not yet follow any standard format\&. However, the \fBdsr2xml\fP application might be enhanced in this aspect in the future (e\&.g\&. by supporting HL7/CDA - Clinical Document Architecture)\&.
.PP
If \fBdsr2xml\fP reads a raw data set (DICOM data without a file format meta-header) it will attempt to guess the transfer syntax by examining the first few bytes of the file\&. It is not always possible to correctly guess the transfer syntax and it is better to convert a data set to a file format whenever possible (using the \fBdcmconv\fP utility)\&. It is also possible to use the \fI-f\fP and \fI-t[ieb]\fP options to force \fBdsr2xml\fP to read a dataset with a particular transfer syntax\&.
.SH "PARAMETERS"
.PP
.PP
.nf
dsrfile-in   DICOM SR input filename to be converted ('-' for stdin)

xmlfile-out  XML output filename (default: stdout)
.fi
.PP
.SH "OPTIONS"
.PP
.SS "general options"
.PP
.nf
  -h   --help
         print this help text and exit

       --version
         print version information and exit

       --arguments
         print expanded command line arguments

  -q   --quiet
         quiet mode, print no warnings and errors

  -v   --verbose
         verbose mode, print processing details

  -d   --debug
         debug mode, print debug information

  -ll  --log-level  [l]evel: string constant
         (fatal, error, warn, info, debug, trace)
         use level l for the logger

  -lc  --log-config  [f]ilename: string
         use config file f for the logger
.fi
.PP
.SS "input options"
.PP
.nf
input file format:

  +f   --read-file
         read file format or data set (default)

  +fo  --read-file-only
         read file format only

  -f   --read-dataset
         read data set without file meta information

input transfer syntax:

  -t=  --read-xfer-auto
         use TS recognition (default)

  -td  --read-xfer-detect
         ignore TS specified in the file meta header

  -te  --read-xfer-little
         read with explicit VR little endian TS

  -tb  --read-xfer-big
         read with explicit VR big endian TS

  -ti  --read-xfer-implicit
         read with implicit VR little endian TS
.fi
.PP
.SS "processing options"
.PP
.nf
error handling:

  -Er  --unknown-relationship
         accept unknown/missing relationship type

  -Ev  --invalid-item-value
         accept invalid content item value
         (e\&.g\&. violation of VR or VM definition)

  -Ec  --ignore-constraints
         ignore relationship content constraints

  -Ee  --ignore-item-errors
         do not abort on content item errors, just warn
         (e\&.g\&. missing value type specific attributes)

  -Ei  --skip-invalid-items
         skip invalid content items (including sub-tree)

  -Dv  --disable-vr-checker
         disable check for VR-conformant string values

specific character set:

  +Cr  --charset-require
         require declaration of extended charset (default)

  +Ca  --charset-assume  [c]harset: string
         assume charset c if no extended charset declared

  +Cc  --charset-check-all
         check all data elements with string values
         (default: only PN, LO, LT, SH, ST, UC and UT)

         # this option is only used for the extended check whether
         # the Specific Character Set (0008,0005) attribute should be
         # present, but not for the conversion of unaffected element
         # values to UTF-8 (e\&.g\&. element values with a VR of CS)

  +U8  --convert-to-utf8
         convert all element values that are affected
         by Specific Character Set (0008,0005) to UTF-8

         # requires support from an underlying character encoding
         # library (see output of --version on which one is available)
.fi
.PP
.SS "output options"
.PP
.nf
encoding:

  +Ea  --attr-all
         encode everything as XML attribute
         (shortcut for +Ec, +Er, +Ev and +Et)

  +Ec  --attr-code
         encode code value, coding scheme designator
         and coding scheme version as XML attribute

  +Er  --attr-relationship
         encode relationship type as XML attribute

  +Ev  --attr-value-type
         encode value type as XML attribute

  +Et  --attr-template-id
         encode template id as XML attribute

  +Ee  --template-envelope
         template element encloses content items
         (requires +Wt, implies +Et)

XML structure:

  +Xs  --add-schema-reference
         add reference to XML Schema 'dsr2xml\&.xsd'
         (not with +Ea, +Ec, +Er, +Ev, +Et, +Ee, +We)

  +Xn  --use-xml-namespace
         add XML namespace declaration to root element

writing:

  +We  --write-empty-tags
         write all tags even if their value is empty

  +Wi  --write-item-id
         always write item identifier

  +Wt  --write-template-id
         write template identification information
.fi
.PP
.SH "NOTES"
.PP
.SS "DICOM Conformance"
The \fBdsr2xml\fP utility supports the following SOP Classes:
.PP
.PP
.nf
SpectaclePrescriptionReportStorage           1\&.2\&.840\&.10008\&.5\&.1\&.4\&.1\&.1\&.78\&.6
MacularGridThicknessAndVolumeReportStorage   1\&.2\&.840\&.10008\&.5\&.1\&.4\&.1\&.1\&.79\&.1
BasicTextSRStorage                           1\&.2\&.840\&.10008\&.5\&.1\&.4\&.1\&.1\&.88\&.11
EnhancedSRStorage                            1\&.2\&.840\&.10008\&.5\&.1\&.4\&.1\&.1\&.88\&.22
ComprehensiveSRStorage                       1\&.2\&.840\&.10008\&.5\&.1\&.4\&.1\&.1\&.88\&.33
Comprehensive3DSRStorage                     1\&.2\&.840\&.10008\&.5\&.1\&.4\&.1\&.1\&.88\&.34
ProcedureLogStorage                          1\&.2\&.840\&.10008\&.5\&.1\&.4\&.1\&.1\&.88\&.40
MammographyCADSRStorage                      1\&.2\&.840\&.10008\&.5\&.1\&.4\&.1\&.1\&.88\&.50
KeyObjectSelectionDocumentStorage            1\&.2\&.840\&.10008\&.5\&.1\&.4\&.1\&.1\&.88\&.59
ChestCADSRStorage                            1\&.2\&.840\&.10008\&.5\&.1\&.4\&.1\&.1\&.88\&.65
XRayRadiationDoseSRStorage                   1\&.2\&.840\&.10008\&.5\&.1\&.4\&.1\&.1\&.88\&.67
RadiopharmaceuticalRadiationDoseSRStorage    1\&.2\&.840\&.10008\&.5\&.1\&.4\&.1\&.1\&.88\&.68
ColonCADSRStorage                            1\&.2\&.840\&.10008\&.5\&.1\&.4\&.1\&.1\&.88\&.69
ImplantationPlanSRStorage                    1\&.2\&.840\&.10008\&.5\&.1\&.4\&.1\&.1\&.88\&.70
AcquisitionContextSRStorage                  1\&.2\&.840\&.10008\&.5\&.1\&.4\&.1\&.1\&.88\&.71
SimplifiedAdultEchoSRStorage                 1\&.2\&.840\&.10008\&.5\&.1\&.4\&.1\&.1\&.88\&.72
PatientRadiationDoseSRStorage                1\&.2\&.840\&.10008\&.5\&.1\&.4\&.1\&.1\&.88\&.73
PlannedImagingAgentAdministrationSRStorage   1\&.2\&.840\&.10008\&.5\&.1\&.4\&.1\&.1\&.88\&.74
PerformedImagingAgentAdministrationSRStorage 1\&.2\&.840\&.10008\&.5\&.1\&.4\&.1\&.1\&.88\&.75
.fi
.PP
.PP
Please note that currently only mandatory and some optional attributes are supported\&.
.SS "Character Encoding"
The XML encoding is determined automatically from the DICOM attribute (0008,0005) 'Specific Character Set' using the following mapping:
.PP
.PP
.nf
ASCII         (ISO_IR 6)                       =>  'UTF-8'
UTF-8         'ISO_IR 192'                     =>  'UTF-8'
ISO Latin 1   'ISO_IR 100'                     =>  'ISO-8859-1'
ISO Latin 2   'ISO_IR 101'                     =>  'ISO-8859-2'
ISO Latin 3   'ISO_IR 109'                     =>  'ISO-8859-3'
ISO Latin 4   'ISO_IR 110'                     =>  'ISO-8859-4'
ISO Latin 5   'ISO_IR 148'                     =>  'ISO-8859-9'
ISO Latin 9   'ISO_IR 203'                     =>  'ISO-8859-15'
Cyrillic      'ISO_IR 144'                     =>  'ISO-8859-5'
Arabic        'ISO_IR 127'                     =>  'ISO-8859-6'
Greek         'ISO_IR 126'                     =>  'ISO-8859-7'
Hebrew        'ISO_IR 138'                     =>  'ISO-8859-8'
Thai          'ISO_IR 166'                     =>  'TIS-620'
Japanese      'ISO 2022 IR 13\\ISO 2022 IR 87'  =>  'ISO-2022-JP'
Korean        'ISO 2022 IR 6\\ISO 2022 IR 149'  =>  'ISO-2022-KR'
Chinese       'ISO 2022 IR 6\\ISO 2022 IR 58'   =>  'ISO-2022-CN'
Chinese       'GB18030'                        =>  'GB18030'
Chinese       'GBK'                            =>  'GBK'
.fi
.PP
.PP
If this DICOM attribute is missing in the input file, although needed, option \fI--charset-assume\fP can be used to specify an appropriate character set manually (using one of the DICOM defined terms)\&. For reasons of backward compatibility with previous versions of this tool, the following terms are also supported and mapped automatically to the associated DICOM defined terms: latin-1, latin-2, latin-3, latin-4, latin-5, latin-9, cyrillic, arabic, greek, hebrew\&.
.PP
Option \fI--convert-to-utf8\fP can be used to convert the DICOM file or data set to UTF-8 encoding prior to the conversion to XML format\&.
.PP
If no mapping is defined and option \fI--convert-to-utf8\fP is not used, non-ASCII characters and those below #32 are stored as '&#nnn;' where 'nnn' refers to the numeric character code\&. This might lead to invalid character entity references (such as '&#27;' for ESC) and will cause most XML parsers to reject the document\&.
.SS "Error Handling"
Please be careful with the processing options \fI--unknown-relationship\fP, \fI--invalid-item-value\fP, \fI--ignore-constraints\fP, \fI--ignore-item-errors\fP and \fI--skip-invalid-items\fP since they disable certain validation checks on the DICOM SR input file and, therefore, might result in non-standard conformant output\&. However, there might be reasons for using one or more of these options, e\&.g\&. in order to read and process an incorrectly encoded SR document\&.
.SS "Limitations"
The XML Schema \fIdsr2xml\&.xsd\fP does not support all variations of the \fBdsr2xml\fP output format\&. However, the default output format (plus option \fI--use-xml-namespace\fP) should work\&.
.SH "LOGGING"
.PP
The level of logging output of the various command line tools and underlying libraries can be specified by the user\&. By default, only errors and warnings are written to the standard error stream\&. Using option \fI--verbose\fP also informational messages like processing details are reported\&. Option \fI--debug\fP can be used to get more details on the internal activity, e\&.g\&. for debugging purposes\&. Other logging levels can be selected using option \fI--log-level\fP\&. In \fI--quiet\fP mode only fatal errors are reported\&. In such very severe error events, the application will usually terminate\&. For more details on the different logging levels, see documentation of module 'oflog'\&.
.PP
In case the logging output should be written to file (optionally with logfile rotation), to syslog (Unix) or the event log (Windows) option \fI--log-config\fP can be used\&. This configuration file also allows for directing only certain messages to a particular output stream and for filtering certain messages based on the module or application where they are generated\&. An example configuration file is provided in \fI<etcdir>/logger\&.cfg\fP\&.
.SH "COMMAND LINE"
.PP
All command line tools use the following notation for parameters: square brackets enclose optional values (0-1), three trailing dots indicate that multiple values are allowed (1-n), a combination of both means 0 to n values\&.
.PP
Command line options are distinguished from parameters by a leading '+' or '-' sign, respectively\&. Usually, order and position of command line options are arbitrary (i\&.e\&. they can appear anywhere)\&. However, if options are mutually exclusive the rightmost appearance is used\&. This behavior conforms to the standard evaluation rules of common Unix shells\&.
.PP
In addition, one or more command files can be specified using an '@' sign as a prefix to the filename (e\&.g\&. \fI@command\&.txt\fP)\&. Such a command argument is replaced by the content of the corresponding text file (multiple whitespaces are treated as a single separator unless they appear between two quotation marks) prior to any further evaluation\&. Please note that a command file cannot contain another command file\&. This simple but effective approach allows one to summarize common combinations of options/parameters and avoids longish and confusing command lines (an example is provided in file \fI<datadir>/dumppat\&.txt\fP)\&.
.SH "ENVIRONMENT"
.PP
The \fBdsr2xml\fP utility will attempt to load DICOM data dictionaries specified in the \fIDCMDICTPATH\fP environment variable\&. By default, i\&.e\&. if the \fIDCMDICTPATH\fP environment variable is not set, the file \fI<datadir>/dicom\&.dic\fP will be loaded unless the dictionary is built into the application (default for Windows)\&.
.PP
The default behavior should be preferred and the \fIDCMDICTPATH\fP environment variable only used when alternative data dictionaries are required\&. The \fIDCMDICTPATH\fP environment variable has the same format as the Unix shell \fIPATH\fP variable in that a colon (':') separates entries\&. On Windows systems, a semicolon (';') is used as a separator\&. The data dictionary code will attempt to load each file specified in the \fIDCMDICTPATH\fP environment variable\&. It is an error if no data dictionary can be loaded\&.
.PP
Depending on the command line options specified, the \fBdsr2xml\fP utility will attempt to load character set mapping tables\&. This happens when DCMTK was compiled with the oficonv library (which is the default) and the mapping tables are not built into the library (default when DCMTK uses shared libraries)\&.
.PP
The mapping table files are expected in DCMTK's \fI<datadir>\fP\&. The \fIDCMICONVPATH\fP environment variable can be used to specify a different location\&. If a different location is specified, those mapping tables also replace any built-in tables\&.
.SH "FILES"
.PP
\fI<datadir>/dsr2xml\&.xsd\fP - XML Schema file
.SH "SEE ALSO"
.PP
\fBxml2dsr\fP(1), \fBdcmconv\fP(1)
.SH "COPYRIGHT"
.PP
Copyright (C) 2000-2023 by OFFIS e\&.V\&., Escherweg 2, 26121 Oldenburg, Germany\&.
